home *** CD-ROM | disk | FTP | other *** search
/ The CICA Windows Explosion! / The CICA Windows Explosion! - Disc 2.iso / programr / dxtw106.zip / SXTNVIEW.DOC < prev    next >
Text File  |  1995-04-10  |  17KB  |  428 lines
  1.  
  2.  
  3.         SXTNVIEW.DOC
  4.  
  5.         SXTNVIEW - SXTN Database Viewer Sample Application
  6.  
  7.         The SXTNVIEW program is  intended  as  a  sample  application  to
  8.         demonstrate  the use of the DLL interface functions to access the
  9.         SXT databases. Each SXT windows version provides its specific DLL
  10.         (CFTNWIN.DLL, CSTNWIN.DLL, ...) together with the necessary C/C++
  11.         header file (CFTNWIN.H,  CSTNWIN.H,  ...) and an  import  library
  12.         (CFTNWIN.LIB,  CSTNWIN.LIB,  ...)  that  can  be  linked  to your
  13.         programs. SXTNVIEW is a very simple application written in Visual
  14.         Basic with complete source code included. SXTNVIEW works with all
  15.         SXT DLL's and demonstrates the access to all SXT database types.
  16.  
  17.         To run SXTNVIEW,  the Visual Basic runtime  library  VBRUN300.DLL
  18.         (not  included  in this package) installed in the \windows\system
  19.         directory is required. It is also necessary to copy the SXT DLL's
  20.         to the \windows\system directory.
  21.  
  22.         After starting SXTNVIEW you have to select the SXT  program  type
  23.         and the database from the file dialog box.  Select one *.dbf file
  24.         that belongs to the project you want to view.  After that you can
  25.         view  in two list boxes the items (functions/data types),  either
  26.         all or only the defined ones,  and the filenames by pressing push
  27.         buttons  next  to these list boxes.  By a double click on an item
  28.         you get its location (filename, line number) where it is defined/
  29.         first found.  By a double click on a filename you get a  list  of
  30.         all  defined  items in that file.  You can also directly type the
  31.         name of an item into the 'Search for' text box and start a search
  32.         with the push button. If an itemname is in the search box you can
  33.         press the 'Get Called Item' button to retrieve  all  items  which
  34.         are called from the item.
  35.  
  36.  
  37.         DLL INTERFACE FUNCTIONS
  38.  
  39.         The  following  description  is  given  for  the  CFT version but
  40.         applies in the same  way to all other SXT programs.  The user who
  41.         calls  one  of  these  functions  has  to ensure that the calling
  42.         parameters are large enough  to  hold  the  resulting  value.  In
  43.         general,  the  strings should be a minimum of 300 characters long
  44.         (char location[300], char name[300], ...).
  45.  
  46.         Some functionality is split into a pair of  two  closely  related
  47.         functions,  like  cftnGetFirstName()  and cftnGetNextName().  The
  48.         user has to ensure that they are called in a direct sequence  and
  49.         that   there   are   no  intermediate  calls,   also  from  other
  50.         applications. Otherwise the results will be incorrect. The reason
  51.         for the split of the functionality is that it is not possible  to
  52.         determine  the  amount  of  memory  to  hold  the  results of the
  53.         function call in advance by the calling function.  It would  have
  54.         been  possible  to  grow  the  memory  dynamically  during search
  55.         operation by the DLL, return a pointer to the memory and leave it
  56.         to the application to free it after use.  This would work with  C
  57.         but  not  with  Visual  Basic or application macro languages like
  58.         Word Basic and Visual Basic for Applications.
  59.  
  60.  
  61.                                       - 1 -
  62.  
  63.  
  64.  
  65.         The return values of all DLL functions are 101 if successful, all
  66.         other values mean that something went wrong  (e.g.  database  not
  67.         found,  database is not a SXT database,  item does not exist, out
  68.         of memory, ...).
  69.  
  70.         Following is a description of the DLL-functions:
  71.  
  72.         LONG FAR PASCAL _export cftnGetLocation(LPSTR dbfname, LPSTR
  73.         name, LPSTR location);
  74.         Get the location of a specific item, if the return value is 101 a
  75.         location for item was found.
  76.              dbfname   the database name
  77.              name      the name of the item
  78.              location  contains a string with the location
  79.                        (filename<space>line number) of the item
  80.  
  81.         LONG FAR PASCAL _export cftnGetFirstName(LPSTR dbfname, LPSTR
  82.         name);
  83.         Get the first item from the database, must be called once before
  84.         cftnGetNextName.
  85.              dbfname   the database name
  86.              name      contains a string with the itemname
  87.  
  88.         LONG FAR PASCAL _export cftnGetNextName(LPSTR dbfname, LPSTR
  89.         name);
  90.         Get the next item from the database, must be called after
  91.         cftnGetFirstName, as long as the return value is 101 a new name
  92.         is retrieved.
  93.              dbfname   the database name
  94.              name      contains a string with the itemname
  95.  
  96.         LONG FAR PASCAL _export cftnGetFirstDefName(LPSTR dbfname, LPSTR
  97.         name);
  98.         Get the first defined item from the database, must be called once
  99.         before cftnGetNextDefName.
  100.              dbfname   the database name
  101.              name      contains a string with the defined itemname
  102.  
  103.         LONG FAR PASCAL _export cftnGetNextDefName(LPSTR dbfname, LPSTR
  104.         name);
  105.         Get the next defined item from the database, must be called after
  106.         cftnGetFirstDefName, as long as the return value is 101 a new
  107.         name is retrieved.
  108.              dbfname   the database name
  109.              name      contains a string with the defined itemname
  110.  
  111.         LONG FAR PASCAL _export cftnGetFirstCalledItem(LPSTR dbfname,
  112.         LPSTR caller, LPSTR calleditem, LPSTR location);
  113.         Get the first called item of caller from the database, must be
  114.         called once before cftnGetNextCalledItem.
  115.              dbfname        the database name
  116.              caller         contains a string with the name of the caller
  117.              calleditem     contains a string with the first called item
  118.              location       contains a string with the location
  119.                             (filename<space>line number) of the item
  120.  
  121.  
  122.                                       - 2 -
  123.  
  124.  
  125.  
  126.         LONG FAR PASCAL _export cftnGetNextCalledItem(LPSTR dbfname,
  127.         LPSTR caller, LPSTR calleditem, LPSTR location);
  128.         Get the next called item of caller from the database, must be
  129.         called after cftnGetFirstCalledItem, as long as the return value
  130.         is 101 a new called item is retrieved.
  131.              dbfname        the database name
  132.              caller         contains a string with the name of the caller
  133.              calleditem     contains a string with the first called item
  134.              location       contains a string with the location
  135.                             (filename<space>line number) of the item
  136.  
  137.         LONG FAR PASCAL _export cftnGetFirstFile(LPSTR dbfname, LPSTR
  138.         filename);
  139.         Get the first file from the database, must be called once before
  140.         cftnGetFirstFile.
  141.              dbfname   the database name
  142.              name      contains a string with the filename
  143.  
  144.         LONG FAR PASCAL _export cftnGetNextFile(LPSTR dbfname, LPSTR
  145.         filename);
  146.         Get the next file from the database, must be called after
  147.         cftnGetFirstFile, as long as the return value is 101 a new file
  148.         is retrieved.
  149.              dbfname   the database name
  150.              name      contains a string with the filename
  151.  
  152.  
  153.         THE VISUAL BASIC EXAMPLE 'SXTNVIEW'
  154.  
  155.         Following is a short, incomplete extract from the SXTNVIEW Visual
  156.         Basic source code to show some implementation details.
  157.  
  158.         1. DLL-FUNCTION DECLARATION
  159.         The DLL-functions have to be declared in the following way:
  160.  
  161.         Declare Function cftnGetLocation Lib "cftnwin.dll" (ByVal
  162.         dbfname$, ByVal searchname$, ByVal location$) As Long
  163.         Declare Function cftnGetFirstName Lib "cftnwin.dll" (ByVal
  164.         dbfname$, ByVal location$) As Long
  165.         Declare Function cftnGetNextName Lib "cftnwin.dll" (ByVal
  166.         dbfname$, ByVal location$) As Long
  167.         Declare Function cftnGetFirstDefName Lib "cftnwin.dll" (ByVal
  168.         dbfname$, ByVal location$) As Long
  169.         Declare Function cftnGetNextDefName Lib "cftnwin.dll" (ByVal
  170.         dbfname$, ByVal location$) As Long
  171.         Declare Function cftnGetFirstCalledItem Lib "cftnwin.dll" (ByVal
  172.         dbfname$, ByVal caller$, ByVal calleditem$, ByVal location$) As
  173.         Long
  174.         Declare Function cftnGetNextCalledItem Lib "cftnwin.dll" (ByVal
  175.         dbfname$, ByVal caller$, ByVal calleditem$, ByVal location$) As
  176.         Long
  177.         Declare Function cftnGetFirstFile Lib "cftnwin.dll" (ByVal
  178.         dbfname$, ByVal location$) As Long
  179.         Declare Function cftnGetNextFile Lib "cftnwin.dll" (ByVal
  180.         dbfname$, ByVal location$) As Long
  181.  
  182.  
  183.                                       - 3 -
  184.  
  185.  
  186.         (similar for the other DLL's)
  187.  
  188.         2. CALLING THE RIGTH SXT FUNCTION
  189.         The SXTNVIEW functions call for  every  DLL-related  function  an
  190.         intermediate function where,  according to the selected SXT type,
  191.         the right DLL-function is  called.  This  simplifies  the  source
  192.         code.
  193.  
  194.         Function sxtnGetFirstName (dbfname$, location$) As Long
  195.           If option1.Value = True Then
  196.             sxtnGetFirstName = cftnGetFirstName(dbfname, location)
  197.           ElseIf option2.Value = True Then
  198.             sxtnGetFirstName = cstnGetFirstName(dbfname, location)
  199.           ElseIf option3.Value = True Then
  200.             sxtnGetFirstName = dftnGetFirstName(dbfname, location)
  201.           ElseIf option4.Value = True Then
  202.             sxtnGetFirstName = fftnGetFirstName(dbfname, location)
  203.           ElseIf option5.Value = True Then
  204.             sxtnGetFirstName = lftnGetFirstName(dbfname, location)
  205.           End If
  206.         End Function
  207.         (similar for the other SXT DLL functions)
  208.  
  209.         3. FUNCTION TO RETRIEVE THE LOCATION OF A SPECIFIC ITEM
  210.         Sub Command2_Click ()
  211.           Dim dbfname As String
  212.           Dim searchname As String
  213.           Dim result As String
  214.           result = String$(300, 0)
  215.           dbfname = label1.Caption
  216.           searchname = text1.Text
  217.           If Left(dbfname$, 1) <> "" And Left(searchname$, 1) <> "" Then
  218.             retval = sxtnGetLocation(dbfname$, searchname$, result$)
  219.             label7.Caption = result$
  220.           End If
  221.         End Sub
  222.  
  223.         4. FUNCTION TO RETRIEVE ALL FILES
  224.         Sub Command3_Click ()
  225.           Dim string1 As String
  226.           Dim result As String
  227.           string1$ = label1.Caption
  228.           result = String$(300, 0)
  229.           list2.Clear
  230.           If Left(string1$, 1) <> "" Then
  231.             retval = sxtnGetFirstFile(string1$, result$)
  232.             If retval = 101 Then
  233.               list2.AddItem result$
  234.               Do
  235.                 retval = sxtnGetNextFile(string1$, result$)
  236.                 If retval = 101 Then
  237.                   list2.AddItem result$
  238.                 Else
  239.                   Exit Do
  240.                 End If
  241.               Loop While retval = 101
  242.  
  243.  
  244.                                       - 4 -
  245.  
  246.  
  247.             End If
  248.           End If
  249.           label6.Caption = Str$(list2.ListCount) + " files"
  250.         End Sub
  251.  
  252.         5. FUNCTION TO RETRIEVE ALL ITEMS
  253.         Sub Command4_Click ()
  254.           Dim dbfname As String
  255.           Dim result As String
  256.           dbfname$ = label1.Caption
  257.           result = String$(300, 0)
  258.           list1.Clear
  259.           If Left(dbfname$, 1) <> "" Then
  260.             retval = sxtnGetFirstName(dbfname$, result$)
  261.             If retval = 101 Then
  262.               list1.AddItem result$
  263.               Do
  264.                 retval = sxtnGetNextName(dbfname$, result$)
  265.                 If retval = 101 Then
  266.                   list1.AddItem result$
  267.                 Else
  268.                   Exit Do
  269.                 End If
  270.               Loop While retval = 101
  271.             End If
  272.           End If
  273.           label5.Caption = Str$(list1.ListCount) + " items"
  274.         End Sub
  275.  
  276.         6. FUNCTION TO RETRIEVE ALL DEFINED ITEMS
  277.         Sub Command5_Click ()
  278.           Dim dbfname As String
  279.           Dim result As String
  280.           dbfname$ = label1.Caption
  281.           result = String$(300, 0)
  282.           list1.Clear
  283.           If Left(dbfname$, 1) <> "" Then
  284.             retval = sxtnGetFirstDefName(dbfname$, result$)
  285.             If retval = 101 Then
  286.               list1.AddItem result$
  287.               Do
  288.                 retval = sxtnGetNextDefName(dbfname$, result$)
  289.                 If retval = 101 Then
  290.                   list1.AddItem result$
  291.                 Else
  292.                   Exit Do
  293.                 End If
  294.               Loop While retval = 101
  295.             End If
  296.           End If
  297.           label5.Caption = Str$(list1.ListCount) + " defined items"
  298.         End Sub
  299.  
  300.         7. FUNCTION TO RETRIEVE ALL ITEMS DEFINED IN A SPECIFIC FILE
  301.         Sub List2_DblClick ()
  302.           Dim dbfname As String
  303.  
  304.  
  305.                                       - 5 -
  306.  
  307.  
  308.           Dim searchname As String
  309.           Dim result As String
  310.           dbfname$ = label1.Caption
  311.           result = String$(300, 0)
  312.           FileName = list2.List(list2.ListIndex)
  313.           list1.Clear
  314.           If Left(dbfname$, 1) <> "" Then
  315.             retval = sxtnGetFirstDefName(dbfname$, result$)
  316.             If retval = 101 Then
  317.               searchname = Left$(result, InStr(1, result, Chr$(0),1) - 1)
  318.               result = String$(300, 0)
  319.               retval = sxtnGetLocation(dbfname$, searchname$, result$)
  320.               If retval = 101 Then
  321.                 If InStr(1, result, FileName, 1) Then
  322.                   list1.AddItem searchname$
  323.                 End If
  324.               End If
  325.             End If
  326.  
  327.             Do
  328.               retval = sxtnGetNextDefName(dbfname$, result$)
  329.               If retval = 101 Then
  330.                 searchname = Left$(result, InStr(1, result, Chr$(0),1)-1)
  331.                 result = String$(300, 0)
  332.                 retval = sxtnGetLocation(dbfname$, searchname$, result$)
  333.                 If retval = 101 Then
  334.                   If InStr(1, result, FileName, 1) Then
  335.                     list1.AddItem searchname$
  336.                   End If
  337.                 End If
  338.               Else
  339.                 Exit Do
  340.               End If
  341.             Loop While retval = 101
  342.           End If
  343.           label5.Caption = Str$(list1.ListCount) + " defined items in "
  344.                                                  + FileName
  345.         End Sub
  346.  
  347.         8. FUNCTION TO RETRIEVE ALL CALLED ITEMS OF A SPECIFIC ITEM
  348.         Sub Command6_Click ()
  349.           Dim dbfname As String
  350.           Dim caller As String
  351.           Dim location As String
  352.           Dim calleditem As String
  353.           dbfname$ = label1.Caption
  354.           calleditem = String$(300, 0)
  355.           location = String$(300, 0)
  356.           caller = text1.Text
  357.           list1.Clear
  358.           If Left(dbfname$, 1) <> "" Then
  359.             retval = sxtnGetFirstCalledItem(dbfname$, caller$,
  360.                                             calleditem$, location$)
  361.             If retval = 101 Then
  362.               list1.AddItem calleditem$
  363.               Do
  364.  
  365.  
  366.                                       - 6 -
  367.  
  368.  
  369.                 retval = sxtnGetNextCalledItem(dbfname$, caller$,
  370.                                                calleditem$, location$)
  371.                 If retval = 101 Then
  372.                   list1.AddItem calleditem$
  373.                 Else
  374.                   Exit Do
  375.                 End If
  376.               Loop While retval = 101
  377.             End If
  378.           End If
  379.           label5.Caption = Str$(list1.ListCount) + " called items"
  380.         End Sub
  381.  
  382.  
  383.         FURTHER DEVELOPMENT
  384.  
  385.         The above example demonstrates the capabilites of the SXT-DLL's.
  386.         They can be called from any Windows application, e.g. MS Word for
  387.         Windows, MS Excel, MS Access, CodeWright Editor, or from user
  388.         developed applications.
  389.  
  390.  
  391.  
  392.         Copyright (C) Juergen Mueller (J.M.) 1988-1995.
  393.         All rights reserved world-wide.
  394.  
  395.         SXT (TM) SOFTWARE EXPLORATION TOOLS
  396.         SXTWIN (TM) SOFTWARE EXPLORATION TOOLS for Windows
  397.  
  398.  
  399.                            (THIS DOCUMENT HAS 7 PAGES)
  400.  
  401.  
  402.  
  403.  
  404.  
  405.  
  406.  
  407.  
  408.  
  409.  
  410.  
  411.  
  412.  
  413.  
  414.  
  415.  
  416.  
  417.  
  418.  
  419.  
  420.  
  421.  
  422.  
  423.  
  424.  
  425.  
  426.  
  427.                                       - 7 -
  428.